EnigmA Amiga Run 1999 January/EnigmA AMIGA RUN 33 (1999)(G.R. Edizioni)(IT)[!][issue 1999-01].iso/earcd/faq/amiga/introduction/part2.z/part2

Text File | 1999-01-01 | 51KB | 1,193 lines

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!newsserver.pixel.kodak.com!frankensun.altair.com!wlbr!news.cerf.net!qualcomm.com!ihnp4.ucsd.edu!swrinde!tank.news.pipex.net!pipex!blackbush.xlink.net!zib-berlin.de!news.uni-ulm.de!news.belwue.de!news.uni-stuttgart.de!uni-regensburg.de!lrz-muenchen.de!informatik.tu-muenchen.de!kellerer
From: [e-mail] (Ignaz Kellerer)
Newsgroups: comp.sys.amiga.introduction,comp.sys.amiga.misc,comp.sys.amiga.programmer,comp.answers,news.answers
Subject: Amiga FAQ (Frequently asked questions) (Part 2 of 4)
Supersedes: <[e-mail]>
Followup-To: comp.sys.amiga.introduction
Date: 9 Apr 1996 16:00:27 GMT
Organization: InternetNews at TUM, Technical University of Munich, Germany
Lines: 1169
Approved: [e-mail]
Distribution: world
Expires: Sunday, 12 May 96 18:00:24 MESZ
Message-ID: <[e-mail]>
References: <[e-mail]>
Reply-To: [e-mail] (Ignaz Kellerer)
NNTP-Posting-Host: hphalle3g.informatik.tu-muenchen.de
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit
Summary: Frequently asked questions on the Amiga.
         New users should read this!
Originator: [e-mail]
Xref: senator-bedfellow.mit.edu comp.sys.amiga.introduction:9126 comp.sys.amiga.misc:118792 comp.sys.amiga.programmer:89201 comp.answers:18061 news.answers:69048

Posted-By: auto-faq 2.4
Archive-name: amiga/introduction/part2
Last-modified: Tuesday, 9. March 1996
Posting-Frequency: ever fourth week


    Frequently asked questions (FAQ) concerning the Amiga. [2/4]
    ------------------------------------------------------------

This is the second part of the Amiga-FAQ. It is in Ascii format to be
easily read by everyone. It is also available in AmigaGuide, Dvi and
html (for WWW servers) format as part of the Amiga-FAQ archive.
(File docs/misc/AmigaFAQ.lha on any Aminet site)

Please note the following:

  - Changes since the last posting are marked with a
    !    changed this line/section, respectively
    +    added this line
    <    removed something before this line

  - An index is at the bottom of this part. If this still doesn't help:
    E-mail me, probably I can include an answer into the FAQ.

  - Suggestions, contributions, critics and beer bottles are very
    welcome. :-) Send them to:

        Ignaz Kellerer
        Georg-Habel-Str. 11
      81241 Muenchen (Germany)
        Tel. (+49) 089 / 885147

        Internet: [e-mail]

===========================(Cut here)=========================================


  Disclaimer

  1 CPU, Custom chips, RAM and other stuff
    1 What are 68EC020, 68EC030 and 68LC040?
    2 What's an FPU?
    3 Can I use a 3.5' HD in my A1200?

  2 The Operating System
    1 Can I use another Kickstart than the builtin?
    2 The Graphical User Interface
    3 What is MUI?
      1 Icon collections and Backgrounds
    4 What is the Amiga equivalent of . (Current directory)?
    5 The PIPE: queue-handler
      1 Using PIPE: in a standard AmigaShell environment
      2 The Pipe command
      3 Pipe command support in AmigaShell
      4 Quick usage guide
      5 Related things
      6 Troubleshooting
    6 ARexx, the program control language

  3 How about Graphics?
    1 What are chunky and planar displays?
    2 What is doublebuffering?
    3 What monitors will work on my Amiga 1200/4000?
    4 How do I switch between PAL and NTSC?

  4 Programming
    1 What documentation do I need as an Amiga programmer?
    2 What is CATS?
    3 Where do I get the Amiga includes?
    4 How do I become a developer?
    5 What compilers (assemblers) are there?
    6 Those never working Esc sequences!
    7 Is it possible to use AmigaBasic on the A1200?
    8 How do I localize my program?
    9 How to obtain a pointer to a console's window
    10 What are pragmas?
    11 My Compiler/Linker is complaining about missing symbol xxx.
    12 Where do I find the function xxx?
    13 The GNU C compiler: general information and installation
      1 Current Version
      2 Requirements
      3 Authors
      4 Sources for Gcc
      5 Inline Headers
      6 Amiga Libraries
      7 Installation
      8 Compiling
      9 How to get help

  5 Applications
    1 Text Editors
    2 What word processors are there?
    3 Desktop Publishing
    4 What is TeX and where can I get it?
    5 Are there any Postscript interpreters?
      1 Amiga Font Formats
      2 Frequently Requested Amiga Fonts
      3 Commercial Font Sources
      4 Non-Latin fonts on the Amiga
      5 Amiga Font Installation
      6 Amiga Font Utilities
      7 Making Outline Fonts
      8 Problems and Possible Solutions
    6 How to deal with Non-Latin texts?
      1 Japanese editors and viewers
      2 Chinese text viewers

  6 Connecting your Amiga to the world

  7 Emulators
    1 Can I run Unix on my Amiga?
    2 Is it possible to use the Amiga as X11 terminal?
    3 Is there a way to start MS-Dos programs?
    4 How to mount MsDos-formatted Syquests on Amiga

  8 Miscellaneous
    1 Is there any unix version of LhA?
    2 What are files ending with ...?
    3 Is there a Stacker-like utility to pack my hard drive?
    4 Where do I get Fish disk xxx?

  9 Where and how do I get software and other informations?
    1 Files and databases on freely distributable software
    2 A collection of tests
    3 Getting files from a FTP server
    4 Getting files from a Mail server
    5 Getting files from a mailbox
    6 The Fish PD series
      1 The Amiga Library disks
      2 The Fresh Fish CD-Roms
    7 How do I Read and write MS-Dos disks?
    8 How do I split large files?
    9 Discussing things
    10 Other FAQ's

  The Amiga-FAQ archive

  Contributions

  Credits

  Index



  4 Programming
  *************

     This chapter handles problems arising for programmers and
  compiler-users only.

  4.1 What documentation do I need as an Amiga programmer?
  ========================================================

     The best information available are the RKMs (ROM Kernel Manuals), 3rd
  edition, by Commodore, published by Addison-Wesley:
       The Amiga ROM Kernel Manual:  Libraries, ISBN 0-201-56774-1
       The Amiga ROM Kernel Manual:  Devices, ISBN 0-201-56775-X
       The Amiga ROM Kernel Manual:  Includes and Autodocs, ISBN
                                                            0-201-56773-3
       The Amiga Hardware Manual, ISBN 0-201-56776-8
       The Amiga User Interface Style Guide, ISBN 0-201-57757-7

  Especially the RKM: Libraries is a must. The RKM: Includes and Autodocs
  isn't that much worth: Better get the same stuff on disk instead to
  have it online.  See Includes.

     AmigaDOS isn't included in these books. The Autodocs give much
  information, but to go deeper you probably need
       The AmigaDOS Manual, 3rd Edition, ISBN 0-553-35403-5
     published by Bantam Books.

     A better choice for developers is
       The Amiga Guru Book

  by Ralph Babel. The book starts with a survey on different aspects of
  programming the Amiga. (About 250 pages) Useful for beginners are the
  sections on the Amiga's data types (not to be confused with the 3.x
  DataTypes used by MultiView, for example), the Includes and the
  amiga.lib. But even experienced programmers will find useful things
  here that are missing in the RKMs.  But the largest part are about 500
  pages on AmigaDOS and, as I think, the most important, because AmigaDOS
  is the worst officially documented part of the OS. The book is rather
  concise and hence not as easy to read as the RKMs, but I recommend it
  as an addition and instead of the AmigaDOS manual.  (Not, however, a
  replacement for the Libraries and Devices, which aren't covered here.)
  Unfortunately the book has no ISBN and is available in special stores
  only. But there are some mail order companies which offer it for about
  50$ and which accept credit cards:

                                   Almathera Systems Limited
                                   Southerton House
       NBG USA, Inc.               Boundary Business Court
       482 Holly Avenue            92-94 Church Road
       St. Paul, MN 55102          Mitcham, Surrey CR4 3TD
       USA                         England
       Voice: [phone]    Voice: [phone]
       Fax:   [phone]    Fax:   [phone]
                                   E-Mail: <[e-mail]>

                                   Stefan Ossowskis Schatztruhe
       Hirsch & Wolf OHG           Gesellschaft für Software mbH
       Mittelstraße 33             Veronikastraße 33
       D-56564 Neuwied             D-45131 Essen
       Germany                     Germany
       Voice: [phone]    Voice: [phone]
       Fax:   [phone]   Fax:   [phone]
                                   E-Mail: <[e-mail]>

       Someware
       27 rue Gabriel Péri
       59186 Anor
       France
       Voice: [phone]
       Fax:   [phone]
       E-Mail: <[e-mail]>
     See FAQs.

  4.2 What is CATS?
  =================

     This is a department at Commodore West Chester which was formerly
  named `Commodore Amiga Technical Support' and was later renamed
  `Commodore Application and Technical Support'. These are people that
  work independently of Engineering, but close together with them, and try
  to help developers outside of Commodore to create nice Amiga
  applications, software or hardware. To achieve this, CATS has gathered
  a lot of informations and tools, on floppy, CD, or paper. Much of this
  material is also available to the general public. (1) But don't mix
  this up with some sort of Hotline for everyone!

     For Americans the address to get this material is
           CATS
           Commodore Electronics Limited
           950 Rittenhouse Road
           Norristown, PA 19403

  for all Europeans it's a company in Germany:
           Fa. Hirsch & Wolf
           Mittelstr. 33
           56564 Neuwied
           Tel. [phone]

     Dr. Peter Kittel, [e-mail]

     ---------- Footnotes ----------

     (1)  Which means: For Non-Developers.

  4.3 Where do I get the Amiga includes?
  ======================================

     The only legal way to get the includes and autodocs (and you *should*
  get them, they are *very* useful!) is to become a developer (see
  Developer) or to buy the `NDU' (Native developers update kit, also
  known as `NDUK' or `NDK'), which is offered by CATS. They cost about
  30$ plus shipping and this seems to me to be a fair price. See CATS.
  The current version is 3.1.

     If you need only the includes, you could get them as well with a
  compiler (commercial compilers only) or by getting the Fresh Fish CD.
  See Fish CD.

  4.4 How do I become a developer?
  ================================

     You need the `ADSP' (Amiga Developer Support Program) documents. To
  get this write a letter to your local Commodore branch asking for these
  documents.  Everything else should be explained there. The german
  address (for the US address see CATS) is
           Commodore
           Lyoner Strasse 38
           60528 Frankfurt
     There are three different developer versions:
  *Registered*
       developers get access to the CBMNET (kind of a Commodore-internal
       Usenet), which makes it possible to discuss problems with other
       developers, Commodore engineers included. Registered developers
       pay about US$80 per year, plus initial US$30 initially.

  *Certified*
       developers seem to me the most interesting claass: They have the
       possibility copy the most beta versions of the system software
       (Kickstart and Workbench) and the respective Includes and
       AutoDocs. (Not all beta versions and especially no beta hardware.)
       You pay about US$250 per year plus US$50 initially for this.

  *Commercial*
       developers finally have in most details the same as certified
       developers, but may expect to get more beta versions and sooner,
       included beta hardware (This has *not* always been so in the
       past.), hencethey pay about US$400 plus US$50 initially.

  The above describes the prices and the situation in Germany and might be
  different elsewhere. Especially not all Commodore branches offer the
  registered status. A hint is to build a group of users and become a
  developer group, so the costs are reduced.

     All developers have to sign non-disclosure agreements (`NDA') which
  specify that we may not discuss information outside of authorized areas
  even to other developers until given explicit permission by Commodore.

  4.5 What compilers (assemblers) are there?
  ==========================================

     There is a lot of programming languages on the Amiga, commercial as
  well as freely distributable. I will enumerate only those that I know
  or which seem it worth to me otherwise.

  *Assembler*
       All C-compilers have an Assembler included. Freely distributable
       are A68K and PhxAss (directory `dev/asm' on Aminet or Fish disks
       521 and 906)

       Commercial Assemblers are MaxonASM, OMA3.0 and DevPack3.14.

  *Basic*
       The following commercial Basic-compiler/interpreter are available:
       BlitzBasic2, Amos and MaxonBasic3.

  *C*
  *C++*
       Freely distributable C-compilers are `gcc' (which has its own
       directory `dev/gcc' on Aminet) and the evaluation version of
       `Dice' (for example per FTP from `ftp.uni-paderborn.de', directory
       `/news/comp.binaries.amiga/volume91/languages' or on Fish disk
       491).  The advantage of gcc is that you find gcc versions all over
       the world and on all computer systems. Another advantage is that
       C++ is included into gcc! But it is slow and needs 4Mb of RAM or
       more.  See The GNU C compiler.  See Mailing lists.

       Commercial C compilers are `Aztec-C', `Dice', `SAS/C' amd
       `MaxonC++'.  `Aztec-C' doesn't seem to get further development any
       more.  It should be remarked that the commercial compilers have
       especially wonderful debugging utilities (Source level debuggers!)
       that the others are missing.

       SAS has announced to drop support of the Amiga-Compiler, too, due
       to the Amiga's bad situation. However, the compiler is still
       available and up-to-date and has a crosscompiler included, which
       translates C++ to C and supports the source level debugger too.
       Considering the price of just 99$ for students and updates from
       recent versions or other compilers it is still the most
       recommendable of the three. In europe the compiler is available
       from
                SAS Institute, Inc.           SAS Institute Gmbh
                Book Sales                    PO Box 10 53 40
                SAS Campus Drive              69043 Heidelberg
                Cary, NC 27513                Germany
                USA

                Phone: [phone]          Phone: [phone]
                EMail: [e-mail]      EMail: [e-mail]

       Dice is the cheapest and fastest commercial compiler. The greatest
       disadvantage of Dice (compared to the other commercial compilers)
       is the so-called Source-Line-Debugger: This means that you see the
       current line of source and can execute the program step by step,
       like with the other debuggers. On the other hand you can examine
       memory only, not the variables.  To get information about DICE,
       send email to [e-mail]. An automatic system will return
       complete details, including upgrade prices.

       Comeau C++ is a crosscompiler like SAS/C++. That wouldn't be a
       problem, but Comeau C++ doesn't have a C compiler included.  You
       need SAS/C, Aztec-C or Dice additionally. But it is AT&T cfront 3.0
       compliant and supports exceptions. And like gcc it runs on many
       platforms.  Maxxon C++ is offered in Germany. I cannot say
       anything on it. Both compilers are commercial. Comeau's address is:
                Comeau computing
                91-34, 120th Street
                Richmond Hill, NY, 11418-3214
                USA

                EMail: Greg Comeau, [e-mail]

       Maxon C++ is both a C++ and a C compiler. There is a light version
       and a developer version. The developer version matches the AT&T
       standard 3.0.  Maxon-light includes a compiler and a editor.
       Developer includes a source level debugger, Amiga classes library
       and Hot Help with documentation to the amiga libs.  It is a german
       product, and compiler and documentation are german.  The compiler
       has some little bugs, but you can work with it well, anyway.

  *Forth*
       JForth is said to be an excellent Amiga port of Forth. Among its
       advantages are object oriented extensions, full Amiga interface
       and an application generator. It is available from:
                Delta Research
                P.O. Box 151051
                San Rafael, CA   94915-1051

                Phone: [phone]
                EMail: Phil Burk, [e-mail]
                       Mike Haas, [e-mail]

  *Fortran*
       (Sigh! Still people who need it :-<) Freely distributable are BCF
       (Fish disk 470) and f2c, a Fortran to C converter (Aminet,
       directory `/dev/lang'). A commercial compiler is offered from
       ABSoft. All these are Fortran 77 compilers, I don't know any
       Fortran 90 compiler on the Amiga.

  *Lisp*
       Freely distributable Lisp interpreters are XLisp (Fish disk 181)
       and OakLisp (Fish disks 519 and 520) and CLISP
       (`/pub/lisp/clisp/binaries/amiga' at the server `ftp
       ma2s2.mathematik.uni-karlsruhe.de'). Lisp compilers are Gambit
       (Fish 764 and 765) and Scheme-to-C (Fish disks 556, 557 and 558).
       See Mailing lists.

  *Prolog*
       `/dev/lang/UNSWProlog.lha' and `dev/lang/sbp3_1e.lha' on Aminet as
       well as `SBProlog' on Fish disk 141 and `SBProlog' on Fish disk
       145 are freely distributable Prolog interpreters.

  *Modula-2*
       M2Amiga is offered in Europe, Benchmark Modula-2 in the U.S. Both
       are said to be very good, have a powerful source-level-debugger, a
       large library.  Especially M2Amiga has great support by a german
       user-group (AMOK) which for example offers own PD disks. See
       Mailing lists.

       M2Amiga is offered by:
                A+L AG
                Daderiz 61
                2540 Grenchen
                Schweiz

                Tel.: [phone]
                Fax:              -79

       Benchmark Modula-2 is available from:
                Armadillo Computing
                5225 Marymount Drive
                Austin, Texas 78723
                USA

                Phone/FAX: [phone].
                EMail: Jim Olinger, [e-mail]

  *Oberon*
  *Oberon-2*
       Two compilers (both Oberon-2) are available: AmigaOberon
       (commercial) is offered by the same company as M2Amiga. It is
       integrated into a full developers environment and has a large
       library of modules.  Library linker and  source level debugger are
       available.

       Oberon-A is a Freeware compiler. (Source: Aminet, `dev/obero'
       directory) However, this is a beta release, especially the module
       library is limited. See Mailing lists.

       The AMOK user group supports AmiOberon as well as M2Amiga.

       In addition to these two standalone compilers which are thought
       mainly for creating AmigaOS applications, there is an Amiga port of
       the Oberon Sytem V4, too. The Oberon System is implemented as an
       AmigaOS-Task using a separate screen and includes an Oberon-2
       compiler. You can use it to write software that will work on all
       implementations of the Oberon System V4 (for example Macintosh,
       Windows or Sparc) without any changes.

  *Pascal*
       There is a PD-compiler called PCQ (Directory `dev/lang' on Aminet
       or Fish disk 511). It doesn't support all of Pascal and major
       features are missing. P2C, a pascal to C converter is on disk 341.
       (Aminet: `/dev/misc/p2c120.lha') Additionally there are two
       commercial compilers called HiSoft Pascal and KickPascal. HiSoft
       Pascal and P2C claim to be compatible to Turbo Pascal up to 5.0.
       HiSoft has a source level debugger included.

  4.6 Those never working Esc sequences!
  ======================================

     Many printers come with a manual that explains which Esc sequence
  causes which action on the printer. But there happen weird things when
  you try to send these sequences to your printer, either it does
  nothing, or it does something completely different. There is a reason,
  the Amiga printer drivers. These drivers are made in a way that they
  only understand a certain set of `ANSI Esc sequences', not the special
  ones defined (differently) by the various printer manufacturers. The
  purpose is that every application on the Amiga just uses this one
  standard set of control sequences and this way doesn't need to know
  which printer is actually connected. The printer driver then translates
  these standard sequences into the special sequences a certain printer
  understands.  A list of the available ANSI Esc sequences is found in
  the current Workbench manuals (or older AmigaDOS manuals). Now if you
  want to issue a control sequence to the printer that's not available as
  an ANSI command, you have two possibilities to achieve this:
    1. Bypass the printer driver (that would unsuccessfully try to
       interpret the sequence) and send your output *only* during this
       sequence to `PAR:' (or `SER:', respectively). For this you have to
       close and open printer output channels very often which is rather
       tedious, and you have to know where (`PAR:' or `SER:') your
       printer is connected.

    2. Use a special ANSI sequence, made exactly for this case:
                `Esc[<n>"<x>'
       where `<n>' is the decimally typed number of bytes in the string
       `<x>', which actually contains your special printer sequence. This
       ANSI sequence tells the printer driver to not interpret or
       translate the next `<n>' bytes.
          But both methods have one big disadvantage when used in an
  application program: You lose the printer independency! If you stick to
  ANSI sequen- ces, you can output to any printer on earth, as long as
  there is an Amiga printer driver for it. If you start to use special
  control sequences, your program will be tied to this single printer
  model and will not be usefull for any other (or you would have to
  provide some dozen new printer drivers for your application).

     Dr. Peter Kittel, [e-mail]

  4.7 Is it possible to use AmigaBasic on the A1200?
  ==================================================

     AmigaBasic wurde (als einziges Amiga-Programm) von Microsoft
  entwickelt und ist entsprechend fehlerhaft.

     Man kann es auf dem A1200 trotzdem zum Laufen bringen, wenn man
  folgendes beachtet:

    1. run NoFastMem (or turn off FastMem).

    2. Switch off sound output in the Sound prefs editor.

    3. Better avoid SUBs and use GOSUBs instead, then the compatibility
       with newer processors will be higher.

    4. There is a patch you should run at the beginning of AmigaBasic:
              ---------------------------------- CUT HERE -------------------------------
               `" AmigaBASIC patch to let AmigaBASIC work on A1200 and other newer machines.
               `" Start at the beginning of AmigaBASIC or invoke AmigaBASIC with this program

               OPEN "AMIGABasic" AS 1 LEN=1
               FIELD #1,1 AS d$
               i&=&HF3*256+&H87 : PRINT i&
               GET #1,i& : a$=HEX$(ASC(d$))
               PRINT a$
               IF a$="79" THEN
                   LSET d$=CHR$(&H78)
                   PUT #1,i&
               END IF
               CLOSE 1
              ---------------------------------- CUT HERE -------------------------------

     Andreas Mixich, [e-mail]

  4.8 How do I localize my program?
  =================================

     Suggest, you want to write a `HelloLocalWorld.c'. Your final program
  will look like this:

           #include "HelloLocalWorld_Cat.h"
           #include <clib/exec_protos.h>

           struct Library *LocaleBase;

           void main(int argc, char *argv[])

           {
               /* Open the locale.library. No kill, if not successfull.
                  (Just use the builtin catalog strings instead.) Note, that
                  we open locale.library here, even if our compiler supports
                  AutoOpening.
               */
               LocaleBase = OpenLibrary("locale.library", 38);
               OpenHelloLocalWorldCatalogs(NULL, NULL);

               printf(GetString(MSG_Hello));

               CloseHelloLocalWorldCatalog();
               if (LocaleBase) CloseLibrary(LocaleBase);
           }

     The routine GetString checks, if the wished catalogs are available
  and returns a pointer to either the builtin string or the catalog
  string. (In my case the german string.)

     You see, the main difference besides the minor opening and closing
  stuff (OpenLibrary, OpenHelloLocalWorldCatalogs, ...) (which too can be
  dropped, too, with FlexCat) is to replace strings with a function call.
  Hence we need a file `HelloLocalWorld_Cat.c', which holds
  OpenHelloLocalWorld, GetString, CloseHelloLocalWorld and the builtin
  strings (this could be an array, where
               array[MSG_Hello] = "Hello, local world.\n";

  is defined) and an include file `HelloLocalWorld_Cat.h', which defines
  the message ID's like MSG_Hello. You don't need to know, how these files
  work internally, especially you don't need to know `locale.library'!

     There are some catalog generators (in what follows: CGs) available
  (`CatComp', for devlopers only, `KitCat', german docs only, `MakeCat',
  which I don't know and `FlexCat', which I  recommend, because it is
  most flexible in the generated source and supports catalogs on 2.0 and
  any language, even Amiga-E, Cluster, Pascal, ... and besides that: I'm
  the author ;-) are tools, that create  HelloLocalWorld_Cat.h,
  HelloLocalWorld_Cat.c and the real catalogs for you. (The above code
  might differ slightly between the different CGs.) (See Aminet, directory
  `dev/misc'.)

     Of course they need to know how to use them. First create a so-called
  `catalog-description' file. This could look like this:
           ; Lines beginning with a semicolon are comment lines.
           # language english
           ; the language of the builtin strings
           # version 0
           ; the catalog version (0 = any)
           MSG_Hello (1/15/30)
           Hello, local world

  Any string is defined by a line like the last two lines above: MSG_Hello
  is the message-ID, (1/15/30) says, that the value of MSG_Hello should be
  1 (you may omit this, in which case just the next free number is used)
  and the string must not be shorter than 15 characters or longer than 30
  characters. (These may be omitted too.)

     Now write your program. Once you are ready, use the CGs to create a
  so-called catalog translation file. (One for any language different than
  the builtin.) In my case (german) this could look like this:
           ; Lines beginning with a semicolon are comment lines.
           ## language deutsch
           ; the catalog language (german)
           ## version $VER: Deutsch.catalog 1.0 (22.12.93)
           ; the catalog files version string
           MSG_Hello

           ; Hello, local world

  Note the empty line after the message ID. (The arguments of ## language
  and ## version would be missing as well.) You have to fill in the
  german strings here. Again using the CGs you create a catalog file from
  this. Additionally note, that no informations on the strings ID or
  length are behind MSG_Hello.  They are taken from the catalog
  description file.

     Once you change the program (adding strings, changing the string
  length) you change the catalog description as well, use the CGs in the
  same way to update the catalog translation and hence the catalogs.

  4.9 How to obtain a pointer to a console's window
  =================================================

     The following function returns the window pointer of a CON window.
  It can be executed safely under all versions of the Amiga's OS.

         struct Window *getConWindowPtr(BPTR fh)
         {
           struct Window *w;
           struct FileHandle *cfh;
           struct StandardPacket *sp;
           struct InfoData *id;
           struct MsgPort *mp;

           w = NULL;

           if ((cfh = BADDR(fh))->fh_Type != NULL) {
             if (sp = AllocMem(sizeof (struct StandardPacket),
                               MEMF_PUBLIC | MEMF_CLEAR)) {
               if (id = AllocMem(sizeof (struct InfoData),
                                 MEMF_PUBLIC | MEMF_CLEAR)) {
                 if (mp = CreatePort(NULL, 0)) {
                   sp->sp_Msg.mn_Node.ln_Name = (char *) &sp->sp_Pkt;
                   sp->sp_Pkt.dp_Link         = &sp->sp_Msg;
                   sp->sp_Pkt.dp_Port         = mp;
                   sp->sp_Pkt.dp_Type         = ACTION_DISK_INFO;
                   sp->sp_Pkt.dp_Arg1         = MKBADDR(id);

                   PutMsg(cfh->fh_Type, &sp->sp_Msg);
                   (void) WaitPort(mp);
                   (void) GetMsg(mp);

                   if (sp->sp_Pkt.dp_Res1)
                     w = (struct Window *) id->id_VolumeNode;

                   DeletePort(mp);
                 }
                 FreeMem(id, sizeof (struct InfoData));
               }
               FreeMem(sp, sizeof (struct StandardPacket));
             }
           }

           return w;
         }

     Notes:
     * Accessing a console's window directly may interfere with operations
       performed by the CON handler. Be careful!

     * To obtain the window pointer of a CLI's console, pass the
       FileHandle returned by Open("*", MODE_OLDFILE) to the above
       function.

     * The result of the above function may well be NULL, e.g. in case of
       an AUX handler or if an AUTO CON handler is unable to open its
       window.

     * Sending an ACTION_DISK_INFO packet to an AUTO CON handler (2.0+)
       causes its window to lose its special AUTO properties (i.e. it can
       no longer be closed at any time by clicking on its Close gadget),
       as the window pointer returned in id_VolumeNode must remain valid
       from now on.

     * All in all: Don't use this function. :-)

     For more information, please refer to pages 273, 276, 435, 463, 485,
  and 629 in "The Amiga Guru Book" (see Manuals).

     Ralph Babel, [e-mail]

  4.10 What are pragmas?
  ======================

     Pragmas are special compiler commmands which control certain
  features of a C-compiler. Two problems arise when using pragmas:
    1. Pragmas are compiler specific. You cannot expect that one compiler
       will understand pragmas of another compiler, even if both run on
       the Amiga.

    2. You are not guaranteed that a compiler ignores pragmas, that he
       doesn't understand. Even more: It might not help, to use something
       like this:
                #ifndef MY_COMPILER
                #pragma DoAnything
                #endif

  A workaround is to put pragmas in a special include file (BTW, the same
  holds true for statements like #asm (Aztec-C) or #extern (C++) and
  replace the above with
           #ifndef MY_COMPILER
           #include <mypragmas.h>
           #endif

     But what do pragmas on the Amiga? The most common usage (not the
  only, but most meant when talking about pragmas) is to tell the
  compiler about how to call library functions: Simple C functions expect
  their arguments on the stack, but library functions want their
  arguments in special processor registers and additionally the `library
  base' in register a6. Lets have a look at a pragma command of the
  Aztec-Compiler.
           #pragma amicall(SysBase,0xd2,FreeMem(a1,d0))

  This tells the compiler to put the first argument of FreeMem in register
  a1, the second in register d0 and the value of the variable SysBase in
  register a6. Maxons pragmas look the same, Dice pragmas and SAS pragmas
  look a bit more complicated;
           #pragma libcall SysBase FreeMem d2 0902

  Here d2 is (like 0xd2 above) the `library vector offset' (see below),
  the digits 09 are codes for the argument register in reversed order
  (Register codes are 0=d0, 1=d1, .., 8=a0, 9=a1, a=a2, ..), the
  following 0 is the result's registerä(always d0))and the final digit 2
  is the number of arguments.

     A command `FreeMem(fib,sizeof(*fib);' could produce the following
  code, if the compiler has seen a pragma statement like above:
           move.l  _fib,a1
           move.l  260,d1        ; sizeof(struct FileInfoBlock)
           move.l  _SysBase,a6
           jsr     -0xd2(a6)       ; 0xd2 = _LVOFreeMem

  Calling FreeMem in that way is shorter and faster than pushing the
  arguments on the stack, calling a function _FreeMem which would do just
  the same like the above code by pulling the arguments from the stack.

     The best way to use pragmas is to include statements like the
  following in your program:
           /*  SAS/C, Dice and GNU-c (since version 2.6.1) make it    */
           /*  very simple:                        */
           #if defined(__SASC)  ||  defined(_DCC)  ||  defined(__GNUC__)
             #include <proto/exec.h>
           #else

             /*  Get the prototype for the function; note, that this    */
             /*  is compiler independent.                */
             #include <clib/exec_protos.h>

             /*  Get the pragma; compiler dependent, but most pragmas    */
             /*  are in files with the same name.            */
             #ifdef AZTEC_C
               #include <pragmas/exec_lib.h>
             #elif defined(__MAXON__)
               #include <pragmas/exec_pragmas.h>
             #endif

             /*  Declare the SysBase variable                */
             extern struct ExecBase *SysBase;
           #endif

  The above example can be compiled on all these compilers and produce the
  best code. (Besides, the proto/*.h-files do nothing else than reading
  clib/*_protos.h and pragmas/*_pragmas.h with #include and then declare
  the SysBase variable.)

     A final question arises: How to get the pragmas? Most compilers have
  them included. However, sometimes you want to produce pragmas for
  yourself, for example if you are using new libraries or new versions
  with additional functions. In that case you can produce them from the
  so-called `FD' files which should be a part of the developer docs of
  the library. (The NDU has a directory FD which contains FD files for
  all libraries and devices of the OS. see Includes) Most compilers have
  a utility with the name `fd2pragma' or similar included which can do
  that for you. A freely distributable version which can produce pragmas
  for Aztec, Dice, SAS and Maxon as well as LVO files for assembler and
  stub routines for the tag versions is available on Aminet
  (`dev/misc/fd2pragma2_0.lha' and on the Fish CDs.

     For pragmas under gcc see Inline Headers.

  4.11 My Compiler/Linker is complaining about missing symbol xxx.
  ================================================================

     First be sure, that the function is really missing: For example
  floating point functions are in a special link library and you need a
  linker option like `-lm' to include it into your program. Another
  possibility would be that you are using a library function and didn't
  notice it. This might lead to a missing library base, `IntuitionBase'
  for example. In that case just put something like
           struct Library *IntuitionBase;

  somewhere in the global part of your program. (Don't forget to call
  OpenLibrary() and CloseLibrary! :-)

     However, you could as well use a function which really isn't present
  in your library at all. If you have, for example, an amiga.lib from 2.0
  you would hardly find the locale functions or the pool memory
  functions. (1) Best solution is to get the NDU (see Includes), but you
  probably don't want to wait for it. In that case you have to find what
  kind of function you are missing.
     * Simple library functions (Examples: `exec/AllocPooled',
       `locale/OpenCatalogA') can be called with pragmas. However, you
       need informations on the name of the library base and where to put
       the arguments. See Pragmas.

     * Tag functions are mostly just stub functions which call library
       functions. If you have, for example, `dos/AllocDosObject' which
       expects a constant and a pointer to an array of tags, you have the
       varargs version `AllocDosObjectTags' which expects tags on the
       stack as well! Just create the following function:
                #include <clib/dos_protos.h>
                #include <pragmas/dos_pragmas.h>    /*  Probably wrong name */

                void *AllocDosObjectTags(ULONG objtype, Tag tag1, ...)
                { return(AllocDosObject(objtype, (struct TagItem *) &tag1);
                }

     * Some functions still remain: Amiga.lib has some functions which
       are really doing valuable things and not just call a library: The
       BOOPSI functions (`DoMethod', `DoSuperMethod') the memory pool
       functions (`LibAllocPooled', `LibCreatePool', which are
       replacements of 3.0 functions). The only way to replace these is
       to get equivalents. The AmigaFAQ archive contains some of them
       (DoMethod, DoSuperMethod and HookEntry) in the `programmer'
       directory as well as the most common pragma files and some
       examples of varargs functions. See Amiga-FAQ Archive.

     ---------- Footnotes ----------

     (1)  This problem arises most frequently for owners of Aztec which
  is no longer supported and owners of Dice, which has sometimes rather
  incomplete libraries. I own both ...

  4.12 Where do I find the function xxx?
  ======================================

     If you are not sure about the name of the appropriate function for a
  certain job or in which library to find it, you can search in these
  places:
     * In the Autodocs for each library you find at the very beginning a
       contents table listing all functions available in this library.
       They are sorted alphabetically, just like in the rest of the
       Autodocs.  In the body part of the Autodocs you find complete
       explanations and specifications for each library function. See
       Includes.

     * The .FD files also offer a very compact overview over all functions
       of the diverse libraries, complete with a short information about
       the function arguments. If you already know roughly what you
       search for and e.g. only need the precise order of the arguments,
       you can find all needed information here. See Pragmas.

     Dr. Peter Kittel, [e-mail]

  4.13 The GNU C compiler: general information and installation
  =============================================================

     This chapter contains general and installation information about the
  amiga-port of the GNU C compiler gcc.

  4.13.1 Current Version
  ----------------------

     Gcc current version is now 2.6.0 and 2.6.1 is in work.  It does
  include a new version of ixemul.library, v40.3, but users are urged to
  get ixemul404.lha on Aminet site or my own FTP site, due to errors for
  68000 systems. A new library, libnix, avoid using ixemul.library.
  2.6.1 will include protos, like SAS-C, making SASC ports to GCC easier.
  A new assembler, gas-2.5 is included, a package called q_anote enables
  output of mixing C/Asm code for debugging purposes.  Work is in
  progress to implement stack growing facility, thus avoiding setting
  stack before launching gcc.

  4.13.2 Requirements
  -------------------

     Any Amiga (ranging from A1000 upto A4000/40) will run amigados-gnu
  utilities. A minimum of 4MB memory is needed in order to compile
  small/medium projects. More memory will be needed for large projects,
  such as recompiling gcc itself, or programming C++. Gigamem and VMM do
  work with GCC so *maybe* less memory will work. But in this case, an
  MMU equipped Amiga (A3000,A4000/40) is necessary.  See 68EC0xx.

     A full installation, including C++/ObjC related files, inline
  headers, cbm-headers, (see Includes) roughly requires about 20 MB of HD
  space.

     Support for 1.2/1.3 is dropped. If you have 1.2/1.3, get a better
  Kickstart version. Gcc works under KS 1.2/1.3, but the full
  functionality is only available under KS 2.x+. A fast CPU (eg.
  68030@25MHz or better) is also of help.

  4.13.3 Authors
  --------------

     Gcc and related GNU-software has been ported to the Amiga by the
  following folks: See How to get help.
           Gcc v2.2.2 port:   Markus Wild
           Gcc v2.3.3 port:   Markus Wild
           Gcc v2.4.5 port:   Philippe Brand, Lars Hecking, Fred Fish
           Gcc v2.5.0 and up: Philippe Brand, Fred Fish, Leonard Norrgard

           Ixemul.library:    Markus Wild, Leonard Norrgard, R. Luebbert
           Libnix:           Matthias Fleischer, Gunther Nikl
               Gerlib:            Gerhard Mueller

  4.13.4 Sources for Gcc
  ----------------------

     All GCC sources & binaries are available on:

    1. Aminet sites (wuarchive.wustl.edu and mirrors such as ftp.luth.se)
       in /pub/aminet/dev/gcc

    2. Ramses The Amiga Flying BBS:
                [phone]  HST Dual v32 terbo 4800-21600
                    [phone]  SupraFax v32bis    4800-14400
                    [phone]  Tornado v22bis     1200-2400
       in Topic `Development', Area `Gcc' (are 156).

     GNU source code is available on:

    1. the same FTP site you've taken the binary distribution from

    2. gnu.prep.ai.mit.edu (18.71.0.38) in `/pub/gnu'

    3. Ramses The Amiga Flying BBS in Topic
       `AmigaUnix/Unix/Linux/NetBSD', Area `Gnu Source Code'

     These archives should contain everything necessary to get you going,
  they don't include sources for ixemul.library, which are available on
  Aminet sites in `/pub/aminet/dev/gcc/ixemsrc3947.tar.gz' (as of this
  writing, work is in  progress for the v40 version of ixemul.library,
  sources will be available on an Aminet site near you).

     As stated by Richard Stallman of the FSF:

     "The GPL says that any distribution of binaries must contain either
  the source code or a written offer to supply source code (see the GPL
  for details of what is required)."

  4.13.5 Inline Headers
  ---------------------

     The inline headers for gcc can be created from the original CBM fd
  files.  See Includes. See Pragmas. They can be created as follows:

       CLI> Assign INCLUDE: GCC:os-include
       CLI> Assign FD: INCLUDE:fd
       CLI> Makedir INCLUDE:inline
       CLI> cd USR:bin/geninline
       CLI> gen31

     This will create all inline-headers in `GCC:os-include/inline'.  If
  you have 2.0 headers, use gen20 instead, if you have 3.0, use gen30.
  OS3.1 (rev 40.13) inline headers are included with the current version
  of gcc. See Current Version.

     NOTE: perl scripts do not handle correctly AmigaDOS include files,
  which seems to mean they are somewhat broken. This needs some voluntary
  work ...

     There is also another way of generating inline headers, using
  fd2inline program:

       CLI> fd2inline <fd_file> <proto_file>

  4.13.6 Amiga Libraries
  ----------------------

     Starting from this release an AmigaDOS compliant library is provided,
  thanks to libnix authors (Matthias Fleischer and Gunther Nikl).

     Anyway if you want to rebuild one, there are two methods:

     1) Using hunk2gcc; the AmigaDOS object converter made by Markus
  Wild. To achieve this, simply grab a copy of latest amiga.lib (from
  Commodore Development Kit, see Includes) and make a new directory where
  you want your converted object files to go, cd into it, and enter

           hunk2gcc amiga.lib [..further libs if you like..]

     This generates an a.out object file for every program unit present
  in the hunk file (in this case, from amiga.lib).

     As the final step convert all those files into an a.out style
  library by issuing:

           ar qc libamiga.a obj.*
           ranlib libamiga.a

     The ranlib run builds a symbol table in the archive, and makes
  accesses to the library much faster.

     2) Creating a libamiga.a library with libnix is fairly easy, but
  takes some time. Just uncompress sources.lha from libnix distribution
  and run a `make libamiga.a'.

     *Note:* As long as you make no AmigaDOS specific calls, you can
  create a dummy library using:

         cat "int dummy;" >dummy.c
         gcc -c dummy.c
         ar crv libamiga.a dummy.o
         mv libamiga.a gcc:lib

  4.13.7 Installation
  -------------------

    1. If this is your first installation of GCC:

       Do the following:

            cd place_with_lot_of_space      ; EDIT! specify one
            makedir gnu
            lha x gcc260-base.lha           ; first part, you need it

       Now you have to append `gnu/s/user-startup' to your
       `s:user-startup' (replace Devel:GNU by your own gnu path).

       Continue:

            execute gnu/s/user-startup      ; makes important assigns
            copy gnu/envarc/#? ENVARC:

       *Edit* the following lines!  If you have a 68000 or 68010 Amiga,
       remove the "-020" from the following lines wherever it appears!

            lha x gcc260-c-020.lha      ; C-compiler part; you need it
            lha x gcc260-doc.lha        ; only if you want Gcc documentation
            lha x gcc260-c++-020.lha    ; only if you want C++
            lha x gcc260-objc-020.lha   ; only if you want Objective-C
            lha x gcc260-utils.lha      ; only if you want additional utilities
                                        ; (recommended for Unix compatibility)
            lha x gcc260-utilsdoc.lha   ; if you want all utilities documentation

       You must restore links between some programs by running the script
       `restorelinks':

            sh /gnu/s/restorelinks      ; EDIT! Append a " copy" to this line
                                        ; if you don't want to use makelink
                                        ; but rather copy file

       Last part:

            lha x gcc260-diffs.lha      ; if you want to rebuild all distribution
            lha x gcc260-texi.lha       ; if you want to build Postscript doc files

       Now skip to next paragraph and happy compiling!

    2. If you "upgrade" your gcc environment from v2.5.x, just unarchive
       first 2 archives as it would normally include all what you need
       (thus gcc260-base and gcc260-c). Make sure you delete your
       previous ixemul.library wherever it is (usually LIBS:).


     *Note*:  new version of ixemul.library is provided, make sure you
  don't have another copy somewhere which may conflict with gcc.

  4.13.8 Compiling
  ----------------

     What about a nice Hello World ?

       #include <stdio.h>

       main()
       {
         printf("Hello World!\n");
       }

     This was pretty simple ;-) Now we have to compile it.  There's a lot
  of options in gcc but simplest way to compile this would be:

       CLI> gcc -o hello hello.c

     Simple ?

     Here's more options.

     Target processor for Motorola family: You can compile plain 68000
  code, 68020, 68030, 68040, 68881 (have a look at GCC documentation,
  either in info or AmigaGuide format, chapter `Invoking Gcc/SubModel
  Options/M680X0 Options for Motorola specific compilation flags').

       CLI> gcc -m68020 -m68881 -o hello hello.c

     This will compile your programs using 68020 code and direct calls to
  math-processor, and will link with accelerated libraries, located in
  `GCC:lib/lib020'.

     Optimization: Either you don't want optimization, or you can provide
  `-O', which will optimize your code, or if you really want top
  optimization, use `-O2' flag (for more discussion about optimization,
  read info or AmigaGuide doc chapter Invoking Gcc/Optimize Options).
  There's now even a `-O3' optimization option, which will go even
  further.

       CLI> gcc -O2 -o hello hello.c

     You'll never have a "Hello World" program running so fast ;-)

     Code generation: Perhaps you want to generate resident programs.
  Flag is -resident, at compile and link stage.

       CLI> gcc -resident -o hello hello.c

     Of course you can mix all options, resulting in:

       CLI> gcc -O2 -m68020 -m68881 -resident -o hello hello.c

     This will make a 68020+68881 executable highly optimized and
  resident.

     IMPORTANT: If you only use AmigaDOS functions or you don't want to
  use ixemul for philosophical reasons, you can get rid of ixemul.library
  with:

       CLI> gcc -noixemul -o foobar foobar.c

     provided you have libnix distribution (included with 2.6.0
  distribution).

  4.13.9 How to get help
  ----------------------

     The current amiga-gcc-port maintainer is available:

           Philippe BRAND
           Fidonet: Ramses The Amiga Flying BBS 2:320/104.21
           Email:   [e-mail] (ONLY for personnal email).
           Ftp:     colombo.telesys-innov.fr:/pub/amigados-gnu
                    or /pub/incoming/uploads for uploads.

     There's also an amiga-gcc mailing list running in Finland.  See
  Mailing lists.  Philippe Brand will forward all questions to that list,
  but you'd be better off using it directly ;)